<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Remote Help proposal for Eclipse 3.3</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
<body>

<h1>
Remote Help proposal for Eclipse 3.3
</h1>

<p>
Curtis d'Entremont, 01/02/2007
</p>

<h2>
The problem
</h2>

<p>
Packaging a comprehensive set of help contents with a product can significantly
increase its size. Consider the eclipse SDK as an example. The download size for
3.2 on Windows is 120MB, of which 30MB is documentation (compressed). This
results in longer downloads, larger media, and more required disk storage.
</p>

<h2>
The solution
</h2>

<h3>
Overview
</h3>

<p>
Host the content on a dedicated server (a plain infocenter) and have each client
workbench access the content remotely. Local content is also allowed and will be
merged with the remote content. The goal is that the help system will behave as
though it were all local, as far as the user is concerned.
</p>

<h3>
Scope
</h3>

<p>
Remote help applies to all forms of help: online help (the documents
themselves, be it html or anything else), table of contents, context help, help
search, and keyword index. Dynamic content (e.g. filters) will still work on
remote content, and will use information from the local machine, not the remote
server. For example, if you have a paragraph to be displayed only on linux, and
you're running the workbench on windows pointing to a remote help server running
on linux, the paragraph will not be shown on the client machine. Since bookmarks
are user-defined and per-user, remote help does not apply and they will continue
to be stored locally.
</p>

<p>
Help should only show remote content pertaining to what the user has installed on
the client side. That is, if the remote help server is used to serve help for
several products, help should filter out all content except for the product(s) the
user has installed.
</p>

<p>
To achieve this, all tocs should specify their enablement based on the presence of
the specific bundle or bundles they are documenting. The same applies to index
content. For example:
</p>

<pre>
&lt;toc label=&quot;User Guide&quot;&gt;
   &lt;topic label=&quot;Getting started&quot;&gt;
      &lt;link toc=&quot;topics_GettingStarted.xml&quot; /&gt;
   &lt;/topic&gt;
   ...
   &lt;enablement&gt;
      &lt;test property=&quot;org.eclipse.core.runtime.isBundleInstalled&quot; args=&quot;my.bundle.name&quot;/&gt;
   &lt;/enablement&gt;
&lt;/toc&gt;
</pre>

<h3>
Precedence
</h3>

<p>
If local content for a particular item is available, it will be used and remote
help will not be consulted. For example, if you attempt to open a specific document,
or open context help on a particular UI, and that document or context help definition
is available locally, it will be used and any remote content for that item will be
ignored. This is for performance.
</p>

<h3>
Configuration
</h3>

<p>
Help needs to know the address (host name/IP) and port of the remote server.
There will be two ways to configure which remote server to retrieve help from:
</p>

<ul>
<li>Global default: Products can be preconfigured to point to a default server
and port. This way the workbench will automatically retrieve remote content upon
startup for the first time.</li>
<li>User preference: A preference page will be available for the user allowing
them to explicitly set or override the host address and port for the remote help
server.</li>
</ul>

<p>
In any case, if no port is specified, a default of 80 will be assumed.
</p>

<h3>
Related enhancements
</h3>

<p>
This is a feature of the reference help implementation provided by eclipse.
There will be no API specifically for this in the help platform
(org.eclipse.help) for help system implementations in general. The API (for
specifying which server to use) will be at the org.eclipse.help.base level
instead. If another implementation of help wishes to do the same, it will be up
to them to implement this support. However the platform API needs to be made
more general in order to support this in the reference implementation. Here are
the known required enhancements:
</p>

<h4>
TOC provider support
</h4>

<p>
Previously the only way to contribute to the TOC (table of contents) was to supply
an XML file in a locally installed plug-in. Since this feature involves having books
contributed from a remote source, this is not enough. To facilitate this, a
general-purpose mechanism was be introduced to make contributions to the TOC.
The API will allow any plug-in to contribute an <code>AbstractTocProvider</code> via an
extension point, which will be queried at runtime to supply TOC information. One
such provider will be contributed by the reference implementation, so authoring
and packaging remote help with this implementation will not require the addition
of any extensions.
</p>

<p>
An <code>AbstractTocProvider</code> is responsible for providing zero or more
<code>ITocContribution</code>s:
</p>

<pre>
/**
 * An <code>AbstractTocProvider</code> is a mechanism to provide arbitrary
 * content to the table of contents (TOC). <code>AbstractTocProvider</code>s
 * must be registered via the <code>org.eclipse.help.toc</code> extension point.
 * 
 * @since 3.3
 */
public abstract class AbstractTocProvider {

	/**
	 * Returns all toc contributions for this provider. Providers
	 * are free to provide any number of contributions (zero or more).
	 * 
	 * @param locale the locale for which to get contributions
	 * @return all the contributions for this provider
	 */
	public abstract ITocContribution[] getTocContributions(String locale);
	
	/**
	 * Notifies the platform that the content managed by this provider may
	 * have changed since the last time <code>getTocContributions()</code>
	 * was called, and needs to be updated.
	 */
	protected void contentChanged() {
	   ...
	}
}
</pre>

<pre>
/**
 * Represents either a complete or partial table of contents, as well as
 * its metadata.
 * 
 * @since 3.3
 */
public interface ITocContribution {

	/**
	 * Returns the contribution's category id. Contributions with the same
	 * category id will be grouped together.
	 * 
	 * @return the contribution's category id.
	 */
	public String getCategoryId();
	
	/**
	 * Returns the symbolic name of the bundle that made this contribution,
	 * e.g. "org.eclipse.help"
	 * 
	 * @return the contributor id, e.g. "org.eclipse.help"
	 */
	public String getContributorId();
	
	/**
	 * Returns the hrefs for any additional documents that are not in this TOC
	 * but are associated with it, and should be indexed for searching.
	 * 
	 * @return any extra documents associated with the TOC
	 */
	public String[] getExtraDocuments();
	
	/**
	 * Returns a unique identifier for this contribution.
	 * 
	 * @return the contribution's unique identifier
	 */
	public String getId();
	
	/**
	 * Returns the locale for this contribution.
	 * 
	 * @return the contribution's locale
	 */
	public String getLocale();
	
	/**
	 * Returns the table of contents data for this contribution.
	 * 
	 * @return the toc data for this contribution
	 */
	public IToc getToc();
	
	/**
	 * Returns whether or not this is a top-level contribution (a book).
	 * 
	 * @return whether the contribution is top-level book
	 */
	public boolean isPrimary();
}
</pre>

<p>
The getId() method is needed here for ordering books in the TOC. In order to
have a way to specify an order of books, whether it be relative or a complete
list, there must be a way to refer to a specific book.
</p>

<p>
The provider must be registered as an extension using the
<code>org.eclipse.help.toc</code> extension point, using the <code>tocProvider
</code> element, as shown below:
</p>

<pre>
&lt;extension
      point=&quot;org.eclipse.help.toc&quot;&gt;
   &lt;tocProvider
         class=&quot;org.example.MyTocProvider&quot;/&gt;
&lt;/extension&gt;
</pre>

<h4>
Keyword index provider support
</h4>

<p>
Keyword index had the same limitation as TOC - the only way to contribute to it
was to provide an XML file in a local plug-in. The solution is be the same as
with TOC, except for keyword content. For example, it will be an
<code>AbstractIndexProvider</code> which supplies <code>IIndexContributions</code>,
and will be registered via the <code>org.eclipse.help.index</code> extension
point using the <code>indexProvider</code>.
</p>

<h3>
Limitations
</h3>

<ul>
<li>A network connection is required.</li>
<li>The performance/responsiveness of help will be limited by the network
connection.</li>
<li>Progress monitoring during indexing may not be as accurate due to the
distributed nature.</li>
<li>Infocenter must be 3.3 or later.</li>
</ul>

<h3>
Future considerations
</h3>

<p>
In the future it may be desirable to allow multiple remote servers instead of
just one. This will be taken into consideration during implementation.
</p>

</body>
</html>
